除了「全方位金流」之外
綠界還有另一支主要的金流規格 - 「站內付2.0」
有些人看了綠界官方文件後，還是不懂從哪裡開始
到底該呼叫哪一支API才能使用「站內付2.0」?
首先，先說說「站內付2.0」與「全方位金流」的不同之處:
全方位金流：用的是Content Type：application/x-www-form-urlencoded
站內付2.0：用的是Content Type：application/json
全方位金流：CheckMacValue
站內付2.0：AES加密
全方位金流：僅需要呼叫一支API，即可喚起付款畫面
站內付2.0：一共有三步驟
接下來就一步步帶大家串起站內付2.0吧!
使用站內付的任何付款方式前，都需要呼叫下面這支API，取得一組token
https://ecpg-stage.ecpay.com.tw/Merchant/GetTokenbyTrade
所有訂單資訊，例如：金額、訂單號碼、消費者資訊、付款方式
都要在呼叫這支API的時決定，如下:
{
"MerchantID": "3002607",
"RememberCard": "0",
"PaymentUIType": "2",
"ChoosePaymentList": "1",
"OrderInfo": {
"MerchantTradeDate": "2024/08/30 10:55:01",
"MerchantTradeNo": "20240830045501",
"TotalAmount": "50",
"ReturnURL": "https://d21b-211-23-76-78.ngrok-free.app/hi/ReturnURL.php",
"TradeDesc": "這裡填入這筆交易的描述",
"ItemName": "這裡填入您的商品名稱"
},
"ATMInfo": {
"ExpireDate": "3",
"ATMBankCode": ""
},
"CardInfo": {
"OrderResultURL": "https://415e-211-23-76-78.ngrok-free.app/hi/OrderResultURL.php"
},
"ConsumerInfo": {
"MerchantMemberID": "",
"Email": "test5555@test.com.tw",
"Phone": "0988555555",
"Name": "",
"CountryCode": "",
"Address": ""
},
"CustomField": ""
}
然後將上述資料進行AES加密驗算後放入Data內
最後連同文件內要求的參數，一併傳送給綠界
實際request的payload長這樣:
{
"MerchantID": "3002607",
"RqHeader": {
"Timestamp": 1724986501,
},
"Data": "udqjXgM+7Q6lCrrculcvzUFnN5zv0ibax1glKFxrORpkePGqlZp2+VtkDaD9WGSHrSEfWfSs1EeCygoF3eTxGsdX4I/xQqOazQgmXzwwDTnVk8Om/Ms6Y0fdxehIy/ssV6lLejv0i+3UxFI3nWEfNHRNVPwNajAFhRVtKlIGX45nFeX4RZsS8sS9bjssL7fWMayFabABGdCuaR64zt/9v/HCFqKsmfaYxg3mL/c9HGw0nISXx2lQ4o0bFbok38wiD9KS2ZKm19pqR9JbZk5d8xjOyfdwPqA0lSBA8fcwjAAQ06uS4ZLFX6MtBlf2XvYyCvByC+rPejZuCdohs2Hg4BjOKC9SkBk8MD31Nu/dFWqG8xcHM4vBq/+dA0Ri5FE8hxziGSM0yFkiVR/uyIOUp7iAy6n8pqJ4lHvp6ZDGf665M0VKuuU12NEAYp0VgQK91GyxKTwuootMp57IpGp1frk+SjnwNNUzqmJ7xtpUf+FxqIF73FllFcFPruvFf+m/9gZrstJXRoOkONhFWDFWhnZX2dpzh+eweMvgaldwmaqyZYmptZearwutj86PbLof1ze3yn1DWx+usj/o4RmlUEDbFDxzvcnaM8NzV/0l/6AsXXV2iSMXESyfLS6RkddNwqGAKEocl82iHgs7qU7Gnug9IMStlZ36SWtHnlQDlaU8EHcKcvBTXbb1KVUMgUvrA/8HTby7iA8bqdpg+g4X/f9mxfnIECi8+BejI4cShEOXyBMYLc1Hp9O1L+cGFKr4lrrCbdxXcNfhbTgJYkpUVIUBgqpCShdIPVQ8GRbZGfjrZSXNIky5eHg44Pt8tNqYSnhxTfbMYfHC2v7cMeyUQvY22kLE+NyW6GRAz1FaeOwOr7KDn4pRrYnfrp4IcpnE6oQNoOdWU0TXwet5oRmcEi+q6r/J6WUu2bE7CGIrnBINuDH8K/n7vtO9etMa+bcciZzhqbvmiSFPGEWg4zdZkdeye2cQW3Hbt90IYZsPYXAPi42jMNOWuLkpE6ZDRVavnPdFbeEHsztHJqOCXfdl059hsENEz1kY/XeHtsreEEoa8ZtHRRsPoPwsKVR6zlQrCa6tNO5m9En3knUiDDHSomro23QCbyXBmvCpFpYRCGn8fxtYh6ZzMlAiL/ijDTkijDx4EEa78PrStu900LkMfpYwC4P77uhI7PCgDjhO4cdy0rim4I1gSMR4uEM1XWD1HQSF8iYLLmNFX9lrafWNEpm6Z7TONTVg8d4N/MlIoojQSJT9JAmO025aeeJfyy7tos95BtBuQ4ZoXHNeFjnkrjri/v6Yzcst5+zRCdYLvwku4+9ovciFocIrRRpgveHkTuunH8p0/A3QioHieSVbRNYbv0kTkNQsC2tFtgEzVb4riLazdJA4UdHISvjm48GzuDZLed6gwbzatFyONv/SsbqPRKylwqBM7Kot2VdE8864o4s2eLsa9/sRoHbJc9XqBo5KVnDBuqOABQ7+PG+u4Q=="
}
(AES加解密方法後面的篇章再來講解，今天先說明流程)
綠界驗算Data無誤後，就會回傳一組token給你:
{
"MerchantID": "3002607",
"RpHeader": {
"Timestamp": 1724986501
},
"Data": "O29c4hMFtVUU3qu5/+w0jGJUI0QIIw8PR51W4dYfKGeWHBKOtbi3mJU4ewThiqmPsKcpktZ1NhlEOiM4Nmv73Pz8XNP9Cfu7X5toMB8oTMq/2Tv+CW3ZEDpP9lhTS4fF5RSbvzCBFYL/gDLGwJ6bgsjVwLO3X/xVi7NqNt9ypyHVrnNqS4th0EnCNZiz4DN7qwNYbrw6T64ujCCCMIA+/pg25VWDueULPdwpSSytjmoLPOC4OgCMNp9Ex9PXKBeKFkjxHMr0ja4SRUgAPio2MugR3WZpVbNwuHrOcxNyvJs=",
"TransCode": 1,
"TransMsg": "Success!"
}
收到上面的綠界回傳後，再自行將Data解密，就可以拿到token囉:
{
"RtnCode": 1,
"RtnMsg": "",
"PlatformID": null,
"MerchantID": "3002607",
"Token": "dee5f34e5f0f408cac760f7fa427dc7e",
"TokenExpireDate": "2024/08/30 11:25:01"
}
拿到token後
接下來就是用這組token來呼叫站內付2.0的畫面
由於是前端畫面，所以要使用綠界web js SDK來呼叫畫面
根據文件所述，在使用JS SDK前有幾個步驟
站內付2.0的畫面會長在ID為ECPayPayment的div標籤內
<div id="ECPayPayment"></div>
也就是說，你想要畫面長在哪裡
就把這行放在你想要的位置就可以囉!
<script src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
因為站內付2.0綠界會用到jquery，所以必須要確實引用
不然會拿到「$ is not a function」錯誤訊息哦
<script src="https://ecpg-stage.ecpay.com.tw/Scripts/sdk-1.0.0.js?t=20210121100116"></script>
這裡有兩點要注意:
<div id="ECPayPayment"></div>
接下來就是初始化綠界WEB JS SDK
ECPay.initialize(ServerType, IsLoading, callBack(errMsg))
ServerType: 因為是測試環境，所以請帶「Stage」
IsLoading: 這裡文件寫「是否顯示等待畫面」，甚麼意思呢?
實際做看看:
「IsLoading=1」: 在畫面跳出來之前，會出現四個小點點，提示用戶畫面加載中:
「IsLoading=0」: 則是在畫面跳出來之前，直接不顯示:
串接的時候再依照各位的需求進行參數調整吧
接下來，取得付款畫面:
ECPay.createPayment(Token, Language, callBack(errMsg), Version)
這裡的Token就是第一步呼叫「Merchant/GetTokenbyTrade」所取回的Token
這裡提醒一點，站內付2.0的畫面也是有效期的，也就是token的到期時間(30分鐘)
超過這個期限，畫面會叫不出來
若是已經叫出畫面，但用戶遲遲未輸入卡號資訊進入下一步，只要超過token的期限一樣會付款失敗
再來就是要自己做一個「付款按鈕」
等用戶輸入完卡號資訊後，按下此付款按鈕後
再呼叫getPayToken()取回一組payToken:
ECPay.getPayToken(callBack(paymentInfo, errMsg))
為了避免用戶尚未填好信用卡號就按下付款鈕，可以自行於前端提示消費者
例如加上「選擇付款方式前請勿按下"確認付款"按鈕」等字樣
成功呼叫getPayToken()後
會取得有效期限為30分鐘的Paytoken以及paymentType
paymentType就是用戶選擇了哪一種付款方式
這裡的意思是，站內付2.0可以同時顯示多種付款方式
例如同時出現信用卡一次付清、信用卡分期、ATM、CVS、Barcode等
用戶最後選了哪一個付款方式會於回傳的paymentType內顯示
到這裡第二步就算完成拉
綠界也很貼心的提供這段範例程式碼:
https://github.com/ECPay/ECPayPaymentGatewayKit_Web/blob/main/Sample.html
有興趣的人可以參照筆者的說明
配合綠界範例一起服用
會更加理解範例程式在做什麼哦
將第二步取回的[PayToken] -- 注意，不是第一步的token
以及第一步填入的[MerchantTradeNo]
加上其他必填參數後呼叫這支API:
https://ecpg-stage.ecpay.com.tw/Merchant/CreatePayment
綠界會回傳一組[ThreeDURL]，也就是3D驗證網址:
請務必記得協助消費者轉跳至該3D驗證網址
讓消費者完成3D驗證完成後
就算完成交易
以上，就是站內付2.0的使用步驟
明天就來說說串接站內付2.0會遇到哪些問題吧
我們明天見
iThome鐵人賽
看影片追技術